HAL OSPI migration: List of applicable concepts ¶

This section provides information about the HAL OSPI applicable architecture concepts.

Concepts for OSPI ¶

Concept	Description
Separation of initialization and configuration functions	The initialization has been split into separate init and config functions: `HAL_XSPI_Init()`: initializes the handle and links it to an OSPI instance. `HAL_XSPI_SetConfig()`: sets the configuration to the XSPI peripheral.
Removal and conversion of init structure to configuration structure	The init structure `OSPI_InitTypeDef` has been removed from the handle and moved into `hal_xspi_config_t` configuration structure.
Renaming of the handle structure	The handle structure has been renamed to `hal_xspi_handle_t`.
Renaming unitary init structures	The `OSPI_InitTypeDef` structure has been replaced by `hal_xspi_config_t`.
Remove MspInit and MspDeInit callbacks	The functions `HAL_OSPI_MspInit()` and `hal_OSPI_MspDeInit()` have been removed and replaced by a user-defined sequence for XSPI initialization and configuration.
Unitary configuration APIs	New APIs have been introduced to get and set XSPI features.
Dedicated DMA link APIs replace generic __HAL_LINKDMA macro	In HAL2, DMA link APIs are provided with explicit naming and parameters : `HAL_XSPI_SetTxDMA()` and `HAL_XSPI_SetRxDMA()`.
Introduction of HAL user data set/get APIs	Two functions are available to set and get user data: `HAL_XSPI_SetUserData()` and `HAL_XSPI_GetUserData()`.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each OSPI event. These functions are used to register callback functions for different OSPI events.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL OSPI driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The OSPI state machine is reworked to ensure transitions of the peripheral functional states.
Revised and optimized HAL API status returns	The HAL OSPI functions were updated to return: `HAL_INVALID_PARAM`: in case of a NULL p_config structure pointer. `HAL_ERROR`: in case of an error. `HAL_TIMEOUT`: in case of a user timeout. `HAL_BUSY`: in case of an ongoing process. `HAL_OK`: in case of a successfully completed operation.
Revised and optimized HAL error management	Add a dedicated function for Error management: `HAL_XSPI_GetLastErrorCodes()`
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL OSPI driver have been removed and replaced by `_t`.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using `ASSERT_DBG_STATE` and `ASSERT_DBG_PARAM` macros.
Add HAL PPP Services for Drivers with Handle to Retrieve Corresponding Peripheral Clock Frequency.	The HAL XSPI driver provides a new API to retrieve the clock frequency: `HAL_XSPI_GetClockFreq()`.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including OSPI instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.

Other HAL OSPI changes ¶

Concept	Description
Split timing fields and memory characteristic fields in the global configuration structure.	User can reconfigure only timing values according to application needs (example : High speed then low speed).
Provide unitary configuration to get `FifoThreashold`	`FifoThreashold` will be configured automatically with the initial value in the SetConfig API.
Split the usage of Hyperbus APIs and regular APIs	Dedicated APIs are provided: Regular: `HAL_XSPI_SendRegularCmd(hal_xspi_handle_t hxspi, const hal_xspi_regular_cmd_t p_cmd, uint32_t timeout_ms)` Hyperbus: `HAL_XSPI_SendHyperbusCmd(hal_xspi_handle_t hxspi, const hal_xspi_hyperbus_cmd_t p_cmd, uint32_t timeout_ms)`

Concept

Description

Split timing fields and memory characteristic fields in the global configuration structure.

User can reconfigure only timing values according to application needs (example : High speed then low speed).

Provide unitary configuration to get FifoThreashold

FifoThreashold will be configured automatically with the initial value in the SetConfig API.

Split the usage of Hyperbus APIs and regular APIs

Dedicated APIs are provided:

Regular: HAL_XSPI_SendRegularCmd(hal_xspi_handle_t *hxspi, const hal_xspi_regular_cmd_t *p_cmd, uint32_t timeout_ms)
Hyperbus: HAL_XSPI_SendHyperbusCmd(hal_xspi_handle_t *hxspi, const hal_xspi_hyperbus_cmd_t *p_cmd, uint32_t timeout_ms)